home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d18 / qwik40.arc / QWIK40.DOC < prev    next >
Text File  |  1991-01-09  |  19KB  |  410 lines
  1.                                                         December 01, 1987
  2.  
  3.                               QWIK SCREEN UTILITIES
  4.                                    Version 4.0
  5.  
  6.         PURPOSE:
  7.  
  8.         QWIK screen utilities permit fast screen writing on IBM 
  9. |       compatibles on any IBM or Hercules adapter including the new PS/2 
  10.         systems without "snow" or flicker effects and is compatible with 
  11. |       ANY column format (e.g. 40/80 or variable).  Written in MASM and 
  12. |       implemented in a unit for Turbo Pascal 4.0, these procedures are 
  13.         lightning fast.  The code has also been condensed as much as 
  14.         possible without sacrificing speed - only 1.6k bytes of compiled 
  15. |       code for all 18 procedures!  QWIK utilities allow you to write to 
  16. |       the screen in absolute coordinates on any video page and are not 
  17. |       confined to a Turbo window or to just page 0.
  18.  
  19.  
  20.         TEST DRIVE:
  21.  
  22.         Compile and run QWIKDEMO.PAS to get a feel for features and speed.
  23.  
  24.  
  25.         IMPROVEMENTS:
  26.  
  27. |       Most obviously, this version was overhauled to work with TP 4.0.  
  28. |       In addition, Hercules and 3270 PC detection was added.  (For those 
  29. |       not familiar with the 3270 PC, it is a stand alone PC that doubles 
  30. |       as a main-frame terminal.)  WhereR and WhereC were added.  CRTcols 
  31. |       and CRTrows variables were added.  TP 4.0 improved string handling 
  32. |       procedures so that Qwrite- no longer requires VAR parameters, so, 
  33. |       QwriteV and QwriteCV were deleted.  Read UPGRADING below on how to 
  34. |       change your source code.  Also, char-type variables can now be 
  35. |       passed to Qwrite- procedures.
  36.        
  37.  
  38.  
  39.         FILES:
  40.  
  41.         In this version, QWIK40.ARC contains:
  42.  
  43.           Qwik40  .tpu:  Compiled QWIK40 unit of 1200 lines of assembler.
  44.           Qwik40  .pas:  Source code for QWIK40.TPU.  (MASM source code 
  45.                          and object files are not included.)
  46.           Qwik40  .doc:  This document.
  47.           QwikDemo.pas:  A demonstration program showing the features and
  48.                          speed of all procedures and is written primarily
  49.                          for color cards, but also works on mono cards.
  50.           Qinit   .doc:  Document for Qinit procedure.
  51.           Qinitest.pas:  A program that verifies the equipment detected
  52.                          by the Qinit procedure.
  53.           Qbench  .pas:  A timing program that shows "screens/second" for
  54.                          the Q- procedures.
  55.           Cursor  .doc:  Document for cursor procedures and functions.
  56.           TimerD12.inc:  Include file to measure elapsed time.
  57.           License .arc:  ARC file containing license agreements
  58.  
  59.  
  60.         PROCEDURES AND FUNCTIONS:
  61.  
  62.         In this version, QWIK40.TPU has the following procedures and 
  63.         functions.  To see the parameters needed, see QWIK40.PAS.
  64.  
  65.           One initializing procedure:
  66.             Qinit        - Initializing procedure executed by QWIK40.TPU 
  67.                            which sets the global variables for the Q- 
  68.                            procedures.  It should be executed again after 
  69.                            a change from one text mode to another.
  70.           Three quick direct screen writing procedures, all work with or 
  71.           without attribute change:
  72.             Qwrite       - for any type string or char.
  73.             QwriteC      - for any type string or char; self-centering.
  74.             QwriteA      - for any type variable; specified length and 
  75.                            index.  (Array-like)
  76.           Four quick direct screen filling procedures in Rows-by-Cols 
  77.           block parameters:
  78.             Qfill        - repetitive filling with the same character;
  79.                            self-centering, with or without attribute 
  80.                            change.
  81.             QfillC       - Same as Qfill, but self-centering.
  82.             Qattr        - repetitive filling with the same attribute 
  83.                            only.
  84.             QattrC       - Same as Qattr, but self-centering.
  85.           Two quick screen storing procedures:
  86.             QstoreToMem  - Saves a Rows-by-Cols block to memory.
  87.             QstoreToScr  - Restores a Rows-by-Cols block to any screen 
  88.                            page.
  89.           Two quick video page changing procedures:
  90.             QviewPage    - Changes the page to be displayed - up to 8!
  91.             QwritePage   - Sets the page on which the Q- procedures are 
  92.                            writing.  You don't have to write just on the 
  93.                            displayed page!
  94.           Six quick cursor procedures and functions:
  95.             GotoRC       - inverse of Turbo's GotoXY but in absolute 
  96.                            coordinates rather than relative to a window.  
  97.                            It also works on any video page.
  98.             ChangeCursor - changes shape and visibility of the cursor; 
  99.                            saves old shape, too!
  100.             CursorOff    - Hides cursor.
  101.             CursorOn     - Reveals cursor, again.
  102.             WhereR       - Returns absolute row coordinate for the viewed 
  103.                            video page.
  104.             WhereC       - Returns absolute column coordinate for the 
  105.                            viewed video page.
  106.  
  107.  
  108.         PROGRAMMING:
  109.  
  110. |       To use QWIK40.TPU in your programs add the following line:
  111. |
  112. |          USES {$U Qwik40.tpu} Qwik;
  113. |
  114. |       Or, if you would like, it is recommended that you copy QWIK40.TPU 
  115. |       to QWIK.TPU and just do this line:
  116. |
  117. |          USES Qwik;
  118. |
  119. |       TP 4.0 Startup - Borland improved the startup of any EXE file.  It 
  120. |       checks for the video mode to see if it is a valid text mode 
  121. |       (0..3,7).  If so, it remains in that mode.  If not, it is in a 
  122. |       graphics mode and it is forced back into the computer's default 
  123. |       text mode, whatever that may be.
  124. |
  125. |       QWIK40 Startup - QWIK40.TPU automatically runs Qinit the first 
  126. |       time.  (Turbo's smart compiler does it just once no matter how 
  127. |       many times it appears in USES statments throughout your program.)  
  128. |       If you change from one text mode to another in a running program, 
  129. |       you still need to run Qinit again. 
  130.  
  131.  
  132.         PARAMETERS:
  133.  
  134.         Row/Col - The procedures do not check for bounds on the screen,
  135.         so be sure to stay in range.  The procedures were designed for
  136.         the upper left column on the screen to be 1,1.  They also wrap to 
  137.         the next line; they do not truncate at EOL.  You of course can 
  138.         have something like Row:=1 and Col:=255 which is equivalent to 
  139.         Row:=3 and Col:=15 on a screen with 80 columns.
  140.  
  141.         ColL/ColR - In QwriteC, QfillC, and QattrC, the left and right 
  142.         columns are simply averaged.  To center on the full width of an 80 
  143.         column display, set ColL:=1 and ColR:=80.  To center on a certain 
  144. |       column number, set both values equal to that column number.  Or, 
  145. |       to center on any display, set ColL:=1 and ColR:=CRTcols.
  146.  
  147.         Rows/Cols - They can be any byte to define the block: Rows-by-
  148.         Columns starting at Row, Col.  Please keep Cols limited to one 
  149.         row.
  150.  
  151.         Attr - The attributes range from 0 to 255.  Values greater than
  152.         255 will be operated by modulo 256 to stay useful.  Negative
  153.         values suppress any changes to the screen attributes and use
  154.         what's currently on the screen.  You can also use Turbo's 
  155. |       TextColor and TextBackground procedures, and then use TextAttr as 
  156. |       a parameter.  Be aware that the 3270 PC ignores the foreground 
  157. |       intensity bit, so there are only 8 colors.  In addition, 4 colors 
  158. |       have different tints:
  159.          
  160. |          PC Color     3270 PC Color
  161. |          ------------ -------------
  162. |          Cyan         Turquoise
  163. |          Magenta      Pink
  164. |          Brown        Yellow
  165. |          Light Gray   White
  166.  
  167. |       ArrayLength - In QwriteA, you can write arrays or partial strings 
  168. |       by specifying the ArrayLength and the starting index (aStr[i]).  
  169. |       (Qwrite and QwriteC assume the length is the value at aStr[0] and 
  170. |       the starting index is aStr[1].)  ArrayLength can be any word.  For 
  171. |       example:
  172. |
  173. |          MyString:='Step B: Testin out this line.';
  174. |          QwriteA (1,1,-1,21,MyString[9]);
  175. |
  176. |       will print out "Testing out this line."  Of course, MyString 
  177. |       doesn't have to be a string - it can be any type variable or 
  178. |       address in memory.
  179.  
  180. |       aStr - One of the nice improvements of TP 4.0 is that the address 
  181. |       of a string is always passed onto to the stack no matter if it's a 
  182. |       string value or a variable.  So, there is no need to copy strings 
  183. |       to the stack and thereby increasing speed.  The Qwrite- procedures 
  184. |       only use the address.  "aStr" is of type "string", now, and not 
  185. |       Str80 and there is no need to be concerned about incompatible 
  186. |       string types
  187.  
  188.         Source/Dest - For Qstores.inc, this can be a pointer for the heap
  189.         or an array variable.  Be sure there is sufficient room.  Storage
  190.         requirements are: (Rows * Cols shl 1) which is two bytes for
  191.         every column.  For pointers use a format such as:
  192.  
  193.             Var  MemPtr: ^byte;
  194.             GetMem (MemPtr,Rows*Cols shl 1);
  195.             QstoreToMem (Row,Col,Rows,Cols,MemPtr^);
  196.  
  197.         Page - The page range depends upon your adapter.  See QINIT.DOC 
  198.         for the possible ranges.
  199.  
  200.  
  201.         PAGING:
  202.  
  203.         If you have a CGA or better, you already have memory on your card 
  204.         for more than the 80x25 display you normally see.  The two page 
  205.         procedures allow you to use QWIK utilities on these other pages 
  206.         and display which ever you choose.  However, Turbo's procedures 
  207.         such as Write, Window, and GotoXY are dedicated to page 0 only.
  208.         Be sure to end your programs with "QviewPage (0);". 
  209.  
  210.  
  211. |       UPGRADING:
  212.  
  213.         Here's a list of steps to help you upgrade to QWIK40 from earlier 
  214.         versions on your new programs:
  215.  
  216.           1. Add "Uses Qwik;" or "Uses {$U Qwik40.tpu} Qwik;".
  217.           2. Delete the first Qinit.
  218.           3. Do a search and replace for the following names.
  219.                Search     Replace with
  220.                ---------  ---------------------
  221.                CardWait   CardSnow
  222.                Qwait      Qsnow
  223.                QwriteLV   QwriteA
  224.                QwriteCV   QwriteC
  225.                QwriteV    Qwrite
  226.                ActiveDD   ActiveDispDev
  227.                AltDD      AltDispDev
  228.                PCCAltDD   AltDispDevPCC
  229.                Vmode      VideoMode
  230.           4. Add "CheckSnow:=Qsnow" early in the program and after each 
  231.              Qinit.
  232.           5. See REVISIONS for changes of type.
  233.  
  234.  
  235. |       TIPS:
  236.  
  237.         CheckSnow - If you plan on using the standard CRT unit, place the 
  238.         following line early in your programs and after each Qinit.
  239.  
  240.            CheckSnow:=Qsnow;
  241.  
  242.         Qinit appears to be more extensive in it's testing for wait-for-
  243.         retrace.  Then, Write and WriteLn will work at the same speed as 
  244.         QWIK if DirectVideo is true.  
  245.  
  246.         Multi-Tasking - Currently, QWIK does not attempt to modify 
  247.         Page0seg for multi-tasking software, but the variables have been 
  248.         set up so you can do this.  Take DESQview for example; rather than 
  249.         writing direct to screen memory, DESQview allocates a presentation 
  250.         buffer in RAM.  All direct screen write procedures can treat the 
  251.         presentation buffer just like the video buffer, except that Qsnow 
  252.         can always be false.  Then, DESQview copies the correct portions 
  253.         to the video buffer.  Here's an example procedure that would 
  254.         modify Page0seg:
  255.  
  256.           uses DOS;
  257.           GetVideoBuffer (VAR Page0seg: word);
  258.           begin
  259.             Regs.es:=Page0seg;
  260.             Regs.di:=0;
  261.             Regs.ah:=$FE;
  262.             Intr ($10,Regs);
  263.             Page0seg:=Regs.es;
  264.           end;
  265.  
  266.         This procedure also works for 3270 PC.  If neither DESQview nor 
  267.         the 3270 PC are present, then Page0seg will still have the same 
  268.         value.
  269.  
  270.         To update the display on the 3270 PC when using multi-tasking, use 
  271.         the following procedure:
  272.  
  273.           UpdateVideoDisplay (Row, Col: byte; NumOfChars: word);
  274.           begin
  275.             Regs.es:=Page0seg;
  276.             Regs.di:=pred(Row)*CRTcols + pred(Col);
  277.             Regs.cx:=NumOfChars;
  278.             Intr ($10,Regs);
  279.             Qseg:=Page0seg;
  280.           end;
  281.  
  282.         where Row and Col is the position in the presentation buffer to be 
  283.         updated and only for NumOfChars.  CardSeg will still have the 
  284.         original segment of the video card.
  285.  
  286.         EgaMono - You should be aware that another constant also named 
  287.         EGAMono is used by the DetectGraph procedure in the Graph unit, 
  288.         but fortunately, they have the same value!
  289.  
  290.         Longer names - If you wish to be more explicit with procedure, 
  291.         function, and variable names, you can always add the unit name as 
  292.         a prefix:
  293.  
  294.            Qwik.GotoRC (1,1);
  295.            MyCols:=Qwik.CRTcols;
  296.  
  297.         Q- Convention - The "Q" in front of a procedure means that it 
  298.         depends on the data initialized by Qinit.  Others do not.
  299.  
  300.  
  301.         SPEED:
  302.  
  303.         How fast is fast?  Well, I thought it would be good idea to have
  304.         some criteria to get a feeling for speed.  The units I decided
  305.         to use for comparison are "screens/second".  To make one screen,
  306.         a procedure is repeated with a FOR loop to fill several 80x25
  307.         pages and timed.  Qwrite- use 80 character strings, and Qattr
  308.         and Qfill use Rows:=25 and Cols:=80.  Here are some samples from 
  309.         the systems that have been tested.  My own computer is the 
  310.         AT&T 6300+ which uses Intel 80286.  Monochrome (MDA) speeds are 
  311.         close to EGA speeds.
  312.  
  313.  
  314.         ------------------ S C R E E N S / S E C O N D ------------------
  315.                    Chng  XT(4.77 MHz)  M50    M30    PCC      ATT 6300+
  316.         Procedure  Attr  EGA     CGA   MCGA   VGA    LCD     EGA     CGA     
  317.         ---------  ----  ------------  -----  -----  -----   -----------     
  318. |       Qwrite      Yes   32.8   9.5    75.4   88.4   40.0   112.1  16.7
  319. |                   No    42.4   9.5    90.0  138.1   48.6   119.5  16.8
  320. |       QwriteC     Yes   32.6   9.5    74.9   89.0   39.5   111.0  16.8     
  321. |                   No    41.6   9.5    89.3  138.1   47.8   119.0  16.8     
  322.         QwriteA     Yes   32.6   9.5    74.9   88.4   39.7   111.3  16.8     
  323.                     No    42.0   9.5    89.3  138.1   47.8   119.5  16.8     
  324.         QfillC      Yes   81.2  11.9   166.6  147.3  122.5   244.3  21.5     
  325.                     No    72.6   7.4   141.3  174.4   90.5   176.9  14.0     
  326.         Qfill       Yes   81.2  11.8   164.1  147.3  122.5   246.1  21.5     
  327.                     No    73.7   7.4   141.3  174.4   90.5   177.9  14.0     
  328.         Qattr       Yes   72.6   7.4   141.3  174.4   90.5   177.9  14.0     
  329.         QattrC      Yes   72.6   7.4   141.3  174.4   90.5   177.9  14.0     
  330.         QstoreToMem n/a   59.1   7.2   111.6  127.4   78.4   181.9  13.8     
  331.         QstoreToScr n/a   59.1   7.0   111.6  126.2   78.4   183.9  13.7     
  332.  
  333.  
  334.         APPLICATIONS:
  335.  
  336.         Multi-level Windows - An application of QWIK40.INC is multi-level 
  337.         windows.  The code is available in a file called WINDOW40.ARC.  It 
  338.         creates protected windows with serial or random access that can be 
  339.         moved or removed and has Macintosh-like special special effects.  
  340.         Scheduled release is 12-12-87.
  341.  
  342.         Multi-level Pull-down Menus - An application of windows is multi-
  343.         level pull-down menus.  I have already created some very thorough 
  344.         code in a file called PULL20.ARC.  It is fully featured and fully 
  345.         configurable.  Includes execute, single, and multiple choice 
  346.         menus, unlimited nested submenus, data entry windows, help 
  347.         windows, directory windows, message system, and fully completed 
  348.         interfaces.  Scheduled release is 01-02-88.
  349.  
  350.         On-line source - All updated files can be found on the CompuServe 
  351.         Borland Forum (GO BPROGA) in the MSDOS TP 4.0 Data Library or the 
  352.         IBM software forum (GO IBMSW) data library.
  353.  
  354.  
  355.         CREDITS:
  356.  
  357.         Without the assistance and original ideas from Brian Foley
  358.         [76317,3247], these routines would not have been written. 
  359.  
  360.         Copyright (c) 1986,1987 by Jim LeMay
  361.  
  362.         If there are any problems, please let me know.
  363.         Jim LeMay [76011,217]  (1-817-735-4833  after 1800 CST)
  364.         6341 Klamath Rd., Ft. Worth, TX, 76116.
  365.  
  366.  
  367.         PRICE:
  368.  
  369.         After much thought, I have decided to make these procedures into 
  370.         ShareWare.  The cost may range from $6 to $16 depending on your 
  371.         application.  I do enjoy assisting others in their programming, 
  372.         but lack of reimbursement is expensive for me!  Please help out.  
  373.         See the license statement, STATMENT.LIC, in LICENSE.ARC for 
  374.         details.  If the response will let me break even, I will continue 
  375. |       support.  Those who have already registered can receive a disk 
  376. |       complete with source code for $2.50, or free if you supply the 
  377. |       disc, mailer and postage.
  378.  
  379.  
  380.         REVISIONS:
  381.  
  382.         Version 4.0 (12-01-87):
  383.           Converted QWIK30 to QWIK40 to work on Turbo Pascal 4.0.
  384.           Deleted QwriteV and QwriteCV.
  385.           Added WhereR and WhereC.
  386.           Added Hercules and IBM 3270 PC detection.
  387.           Renamed the following variables:
  388.             From       To
  389.             ---------- ------------
  390.             CardWait   CardSnow
  391.             Qwait      Qsnow
  392.             QwriteLV   QwriteA
  393.             QwriteCV   QwriteC
  394.             QwriteV    Qwrite
  395.             ActiveDD   ActiveDispDev
  396.             AltDD      AltDispDev
  397.             PCCAltDD   AltDispDevPCC
  398.             Vmode      VideoMode
  399.           Added the following variables:
  400.             VideoPage, CRTcols, CRTrows, CardSeg, Have3270, 
  401.             ActiveDispDev3270
  402.           Added the following constants:
  403.             NoHerc, HgcMono, HgcPlus, HercInColor
  404.           Types were changed on the following items:
  405.             - Strings passed to Qwrite- are of type String rather 
  406.               than Str80.  (Should not be of any consequence.)
  407.             - The CursorChange parameters are now word.
  408.             - EgaFontSize, CRTcolumns, CardSeg, Page0seg, Qseg, 
  409.                   AltDispDevPCC and ArrayLength are now word.
  410.